✅ Deploy Preview for gardener-docs ready!

Name	Link
🔨 Latest commit	36ac829
🔍 Latest deploy log	https://app.netlify.com/projects/gardener-docs/deploys/6a5a55fb284b7300084a592f
😎 Deploy Preview	https://deploy-preview-1004--gardener-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands.}

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign dimitar-kostadinov for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Core Problems in the Documentation

1. Conceptual overload without a simple mental model

The doc immediately introduces:

• many credential types (CAs, SSH, ETCD, service accounts, observability, cloud keys),
• two ownership models,
• and a two‑phase rotation model

➡️ But it never gives a simple “big picture” first.

Impact: Stakeholders cannot answer basic questions like:

• “What exactly am I rotating?”
• “Why would I need this?”
• “Which path applies to me?”

✅ What’s missing:

• A 1-paragraph explanation of the problem rotation solves
• A diagram or flow (who rotates what and when)

2. Two completely different processes are mixed together

The doc contains two fundamentally different workflows:

A. Gardener-managed credentials

• rotated via annotations
• two-phase model

B. User-provided credentials (cloud keys)

• rotated by updating secrets
• no phases
• async reconciliation

➡️ These are described in the same flow, with weak separation.

Impact: Users blend the models incorrectly, e.g.:

• Expect phases for cloud credentials ❌
• Expect annotations for cloud credentials ❌
• Don’t understand why one is manual vs automatic ❌

✅ What’s missing:

• A hard separation with decision logic, e.g.:

START HERE:
Are you rotating cloud provider credentials?
 → Yes → Follow process A
 → No → Follow process B

3. The “two-phase rotation” is explained abstractly, not operationally

The documentation says:

• “prepare phase”
• “complete phase”
• “update clients in between”

But it does NOT clearly answer:

• Who are the clients?
• What exactly must be updated?
• How do I know I’m ready for “complete”?
• What breaks if I don’t?

➡️ It explains mechanics, not usage.

Impact: Stakeholders don’t trust the process because:

• It feels risky
• It lacks operational checkpoints

✅ What’s missing:

• A real scenario, e.g.:

“If you rotate the CA, kubeconfigs must be redistributed before completing.”

4. Too much Kubernetes-native detail, not enough user intent

Examples:

kubectl annotate shoot ...
.status.credentials.rotation
.spec.maintenance.autoRotation.credentials

➡️ These are implementation details, not user guidance.

Impact:

• Non-expert users get lost
• Even experts must mentally reconstruct the workflow

✅ What’s missing:

• Step-by-step flows like:
  1. Trigger rotation
  2. Wait for condition X
  3. Update Y
  4. Verify Z
  5. Complete rotation

5. Ambiguous ownership messaging

Table says:

➡️ Both say “You” → this is misleading.

Impact: Users ask:

• “What exactly does Gardener automate then?”

✅ Reality (not clearly expressed):

• Gardener executes rotation
• User controls timing and readiness

✅ What’s missing:

• Clarification like:

“Gardener performs the mechanics, but you are responsible for safe rollout decisions.”

6. No clear failure modes or risks

The doc never clearly explains:

• What happens if you:
  • don’t update clients before “complete”
  • delete credentials too early
  • rotate in wrong order

➡️ This is critical for operational confidence.

Impact:

• Stakeholders hesitate to use the feature
• Or worse → misuse it

7. User-provided credentials section is underspecified

It says:

• Update secret
• Wait for reconciliation
• Delete old keys

But lacks:

• timeline expectations
• verification steps
• multi-shoot implications

➡️ Especially weak for shared credentials.

8. Repetition without clarity improvement

The update repeats ideas like:

• “prepare phase adds new credentials”
• “complete phase removes old credentials”

➡️ But repetition ≠ clarity

Impact:

• The doc is longer but not clearer
• Key insights are still missing

9. No concrete examples

There are zero real-world scenarios, such as:

• Rotating CA → kubeconfigs impacted
• Rotating SSH key → node access impact
• Rotating ETCD encryption → no client action

➡️ All credentials are treated generically, but they behave very differently.

🧠 Why Stakeholders Still Don’t Understand It

1. They think in tasks, not in systems

They want:

“I need to rotate cloud credentials safely — what do I do?”

But the doc answers:

“Here is how credential systems work internally”

2. They need decision guidance, not reference text

Missing:

• decision trees
• “when to use what”
• “which applies to me”

3. The doc assumes deep Gardener/Kubernetes knowledge

Concepts like:

• Shoot
• reconciliation
• maintenance window

are not re-explained.

4. It lacks operational confidence signals

No:

• checklists
• validation steps
• “safe to proceed” markers

✅ What Would Fix It

1. Add a decision entry point

Which credentials do you want to rotate?
[ ] Cloud provider credentials → go here
[ ] Cluster internal credentials → go here

2. Split into two completely separate guides

• Guide A: Cloud credentials (simple, linear)
• Guide B: Gardener-managed credentials (phased, more complex)

3. Add worked examples

At least:

• CA rotation
• SSH key rotation
• Cloud credential rotation

4. Add checklists

Example:

Before completing rotation:

• All kubeconfigs updated
• All clients using new CA
• Verification successful

5. Add a diagram

Visualizing:

• prepare → coexistence → complete
• or user vs gardener responsibilities

🟢 Bottom line

The documentation improved accuracy, but not usability.

👉 The real issue is not missing information
👉 It’s missing structure, decision guidance, and operational clarity

That’s why stakeholders still say:

“I read it, but I don’t know what to actually do.”